---
title: Operational runbook
summary: Invocation, scheduling, logs, exit codes, error scenarios, and recovery procedures for OnBaseKeywordSync.
status: draft
owner: Documents
last_reviewed: 2026-09-17
---

# Operational runbook

OnBaseKeywordSync is invoked with no arguments, runs a single Execute-stage batch operation, and produces a binary success/failure exit code (`0` or `5`). This page collects the operational facts an on-call engineer needs to triage a failed or unexpected run.

## Invocation

```
OnBaseKeywordSync.exe
```

The application declares no command-line arguments. See [Arguments](arguments.md) for the full (empty) contract.

### Arguments

| Argument | Example | Required | Notes |
| --- | --- | --- | --- |
| *(none declared)* | `OnBaseKeywordSync.exe` | — | The application takes no input; all behavior is driven by environment configuration. |

## Scheduling

| Attribute | Value |
| --- | --- |
| Frequency | Not determined from source |
| Typical start time | Not determined from source |
| Expected duration | Not determined from source |
| Scheduler job name | UC4 (per `README.md`: "run from UC4", "Called from many different UC workflows"); no job definition file exists in this repository |
| Upstream dependencies | Not determined from source |
| Downstream dependents | Not determined from source |

`Pipelines/build.yml` and `Pipelines/release.yml` both declare `trigger: none` and contain only build/deploy stages; no scheduler definition file exists in this repository.

## Console output

| Output | Source | Notes |
| --- | --- | --- |
| `Running as: <userId> on track: <track>` | `ProgramRunnerBase` | Identity and environment track echo† |
| `OnBaseKeywordSyncRunner began at <time>` / `ended at <time>` | `ConsoleBase` header/footer | `ApplicationName` is not overridden, so it defaults to the runtime type name `OnBaseKeywordSyncRunner`*; includes total running time† |
| `"OnBase Keyword Sync execution started."` | `OnBaseKeywordSyncRunner.Execute` | First application log line |
| `"Updates will be sent to OnBase {asynchronously\|synchronously}"` | `OnBaseKeywordSyncRunner.Execute` | Echoes the resolved `OnBaseKeywordSync.onbaseasync` mode |
| `"Found {n} unprocessed image_keyword_sync records with a total of {m} total docs to update."` | `OnBaseKeywordSyncRunner.Execute` | Batch size summary |
| Per-record blocks (ID, trigger type, doc type group, keyword, prior/new value, send/skip reason, update result) | `KeywordUpdater` | See [Operations and processes](operations-processes.md) |
| `Exit Code: <n>` | `SaifStandardProgramBase` | Final line of every run† |

## Log files

Log destinations are configured through **machine-level environment variables** `file0`–`file4` on the host that runs the executable. Each variable's value is a log file path.† These are simply named log-file destinations — an application convention, not a control/detail/error stream contract.

| Environment variable | Content | Retention |
| --- | --- | --- |
| `file0`–`file4` | Not used — the application registers no log file explicitly and assigns no specific role to any id. Whatever is registered receives every `Write`/`WriteError` message† | Not determined from source** |

A separate debug-only tee writes to `C:\temp\OnBaseKeywordSync_Debug.log` (from `appSettings` key `debugLogFile`) only when a debugger is attached, and the file is truncated at every process start regardless of debugger state — see [Tech debt](tech-debt.md).

## Environment configuration

| Setting | Key | Purpose |
| --- | --- | --- |
| Async mode | `OnBaseKeywordSync.onbaseasync` | Whether updates are sent to OnBase synchronously or asynchronously |
| Imaging API base URL | `imagingapiurl` | Base URL for the Imaging API `ImageKeywordSyncs` endpoints |
| Imaging API timeout | `onbasekeywordsync.imagingClientTimeoutSeconds` | Imaging API response timeout in seconds |
| Document counting | `OnBaseKeywordSync.getdocumentcount` | Whether to check/log document counts before sending an update |
| OnBase endpoint | `OnBaseKeywordUpdateServiceUrl` | OnBase SOAP keyword-update service address |
| OnBase throttle | `OnBaseKeywordSync.onbaseclientsleepmilliseconds` | Milliseconds to sleep between OnBase calls |
| Custom query mapping | `OnBaseKeywordSync.customquerymappings` | Doc-type-group-to-custom-query mapping string |

See [Configuration](configuration.md) for the complete settings catalog.

## Exit codes

| Code | Meaning | Operator action |
| --- | --- | --- |
| 0 | Success | None |
| 1 | Invalid or missing argument | Not used — no arguments are declared* |
| 2 | Database error | Not used — no database access exists |
| 3 | Invalid data encountered | Not used |
| 4 | File read/write failure | Not used |
| 5 | Unhandled exception | Escalate with the formatted exception from standard error — the only failure code this application produces. Typical causes: Imaging API HTTP failure, OnBase WCF fault/timeout, missing `customquerymappings` entry for a doc type group, or a configuration key that fails to convert |
| 6 | No data found | Not used — an empty unprocessed set logs a zero-record summary and exits `0` |

## Error scenarios

| Scenario | Symptom | Impact | Recovery |
| --- | --- | --- | --- |
| Imaging API unreachable or returns an error | Exception during `ImagingApiClient` calls, `"Error syncing OnBase claim data.  Error: {ex.Message}"` on stderr, exit code 5 | No records processed for this run | Verify `imagingapiurl` for the configured track and Imaging API availability, then re-run |
| OnBase SOAP endpoint unreachable, faulted, or times out | WCF exception, exit code 5 | Batch aborts mid-run; records already marked processed are not rolled back* | Verify `OnBaseKeywordUpdateServiceUrl` and OnBase service availability, then re-run; manually reconcile any records marked processed without a confirmed OnBase update |
| Doc type group missing from `customquerymappings` | `KeyNotFoundException`, exit code 5 | Batch aborts at the first unmapped record | Add the missing `DTG\|query` pair to `OnBaseKeywordSync.customquerymappings` for the affected track, then re-run |
| `onbaseasync` missing or non-boolean | Conversion exception, exit code 5 | Application aborts before any record is processed | Verify the `OnBaseKeywordSync.onbaseasync` value is declared and boolean for the configured track |
| One record's update fails mid-batch | Exception propagates, exit code 5 | Remaining records in the batch are never evaluated; there is no per-record error isolation* | Investigate the failing record, correct the underlying data or configuration, then re-run — already-processed records are not resent |
| `enttest8` track malformed settings | Three settings (`getdocumentcount`, `onbaseclientsleepmilliseconds`, `customquerymappings`) have no declared value on `enttest8` due to a `false:`/`value:` YAML defect | Behavior on that track depends on undetermined fallback behavior** | Fix `environmentsettings/settings.yml` to use `value:` instead of `false:` for the three `enttest8` entries |

## Monitoring and alerting

| Alert | Trigger | Recipient | Severity |
| --- | --- | --- | --- |
| Job failure | Exit code `5` (non-zero) | Documents team on-call | High — the only failure code this application produces |

## Related documentation
- [Application index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Run lifecycle](run-lifecycle.md)
- [Arguments](arguments.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `†` are derived from dependency library documentation via the Legends CLI. Statements marked with `*` were inferred from code structure or contextual evidence. Statements marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- `README.md`
- `OnBaseKeywordSync/OnBaseKeywordSyncRunner.cs`
- `OnBaseKeywordSync/Services/ImagingApiClient.cs`
- `OnBaseKeywordSync/Services/OnBaseKeywordSyncClient.cs`
- `OnBaseKeywordSync/Extensions.cs`
- `OnBaseKeywordSync/App.config`
- `environmentsettings/settings.yml`
- `Pipelines/build.yml`
- `Pipelines/release.yml`